# Tutorial

## blink with LED

This is platform-neural tutorial, although hardware implementation refers to
arduino. The full code can be found at `examples/atmega328p/blink-led.cpp`. In
this example the blinking with LED is performed using
[rotor-light](https://notabug.org/basiliscos/cpp-rotor-light).

Let's start from the inclusion of headers:

~~~{.cpp}
#include <rotor-light.hpp>
~~~

All further interactions with the framework is done via `rl` namespace

~~~{.cpp}
namespace rl = rotor_light;
~~~

In this example, there is only single message - `BlinkCommand`. It is good
practice to define messages in it's own namespace, as it is much more
convenient to deal with messages later (handle and send).

~~~{.cpp}
namespace message {

struct BlinkCommand : rl::Message {            // (1)
  static constexpr auto type_id = __LINE__;    // (2)
  using rl::Message::Message;                  // (3)
} // namespace message
~~~

The `BlinkCommand` message have to be derived from `rotor_light` `Message` (1),
and as the `BlinkCommand` has no payload, it just reuses its parent
constructor (`using rl::Message::Message`, (3)).

As the `rotor_light` does not use RTTI it should somehow identify
message types at runtime, the `type_id` (2) field helps with that. 
`rotor_light` does not care how you, as the user, define your message 
type, the only requirement is the uniqueness of them. The easiest way to
achieve that is just have line (2) in every message type definition, and 
group all used messages in a single header file.

Let's move to the blinker actor code; as it is rather small, it is shown
entirely:

~~~{.cpp}
struct Blinker : rl::Actor<2> {  // (5)
using Parent = Actor<2>;         // (6)

void initialize() override {              // (7)
  subscribe(&Blinker::on_blink_command);  // (8)
  Parent::initialize();                   // (9)
}


  void advance_start() override {  // (10)
    Parent::advance_start();       // (11)
    blink();                       // (12)
  }

  void blink() {
    toggle_led();                                                         // (13)
    add_event<rl::ctx::thread>(delay, [](void *data) {                    // (14)
        auto self = static_cast<Blinker *>(data);                         // (15)
        self->send<rl::ctx::thread, message::BlinkCommand>(0, self->id);  // (16)
    }, this);
  }

void on_blink_command(message::BlinkCommand &msg) {  // (17)
  blink();
}

rl::Duration delay;  // (18)
};
~~~

First, your own actor have to inherit from `rl::Actor` (5). The magic number `2` is
used for preallocation of space for actor's message handlers: one handler from
the base class defined by the framework (might be changed in the future), and the
other one use the user-provided `on_blink_command`. The alias (6) makes it more
convenient to refer the base class in the future.

To react on the `BlinkCommand` message, the actor should subscribe to it (8). The
proper place to do that is to override `initialize()` method (7) of the parent class.
Of course, parent class **must** be initialized too, that's why don't forget to
invoke its initialization (9).

When actor is ready, its `advance_start()` (10) is invoked; as usually corresponding
parent method should be called (11) and the initial blink (12) is performed. In
the implementation of `blink()` the platform-dependent LED toggle is done at (13),
and then delayed the same method invocation is scheduled (14-16). In (14) the
capture-less lambda is scheduled to be invoked with `this` as the parameter when
`delay` (18) amount of time passes. The lambda *must* be capture-less. After casting
back `void*` to the actor class (15), it sends self a `BlinkCommand` message (16)
using zero-priority queue. The `id` parameter is the destination actor address;
which is the `Blinker` (self) address here. The destination address can also be
multiple actors (i.e. it is mask).

The `rl::ctx::thread` in (13) and (16) gives hints, wether interrupts should 
(`ctx::thread`) or not (`ctx::interrupt`) be masked during methods invokations.
The `ctx::thread` masks and then unmasks all interrupts, so, generally it
should not be called from interrupt context. The last one (`ctx::interrupt`) 
does not touches CPU interrupt enablence flag. 

Each time the `BlinkCommand` is received (17), the `blink()` method is invoked, and
the procedure above repeats again.

Next, the application-wide compile-time configuration should be made:

~~~{.cpp}
using Storage = rl::traits::MessageStorage<rl::message::ChangeState,    // (18)
                                           rl::message::ChangeStateAck,
                                           message::BlinkCommand>;
using Queue = rl::Queue<Storage, 5>; /* upto 5 messages in 1 queue */   // (19)
using Planner = rl::Planner<2>;      /* upto 2 time events */           // (20)
using Supervisor = rl::Supervisor<                                      // (21)
                            rl::SupervisorBase::min_handlers_amount,
                            Blinker>;
~~~

[rotor-light](https://notabug.org/basiliscos/cpp-rotor-light) uses queues to
store and process messages. There are no dynamic allocations, so, all sizes have
to be known at compile-time, including the sizes of all used messages. The
`Storage` helper (18) is used to determine the maximum allowed space size per
message: here **all messages** in the application should be enumerated, i.e.
messages from the framework and user-defined.

Next, the application queue (or master queue) should be defined (19). It uses
`Storage` and the magic number `5`, which pre-allocates space for queue with
**zero-priority** for 5 messages. All [rotor-light](https://notabug.org/basiliscos/cpp-rotor-light)
messages are put into that queue by default, user-defined messages might use
different queues. Queues with higher priorities are processed earlier than
queues with lower priorities. So, to define master queue with two subqueues
(priorities 0 and 1) with sizes enough to store 15 and 10 messages respectively,
the following code should be used

~~~{.cpp}
using Queue = rl::Queue<Storage, 15, 10>;
~~~

What is the recommended queue sizes? Well, it is completely application defined, but
for [rotor-light](https://notabug.org/basiliscos/cpp-rotor-light) messages there
should be enough space to store `N * 2` messages, where `N` is the total number of actors (including supervisors).

What happens, if a queue is full? The next send message is simply discarded, you'll
be notified about that as the `send()` method returns `false`. If the discarded
message is [rotor-light](https://notabug.org/basiliscos/cpp-rotor-light) message,
then *the framework behavior is undefined* (more strictly speaking, overridable
`void rotor_light::on_queue_full()` method is invoked). So, either do not overload
default queue (i.e. with zero-priority), or use different  queues for user-messages.
NB: there is a spike of [rotor-light](https://notabug.org/basiliscos/cpp-rotor-light)
messages only during (re)starting supervisor; when everything is *operational*
there is almost no framework messages.

The Planner (20) is used to schedule future events, like it is shown at `add_event`
(13). The number in angle braces (20) defines planner capacity at compile-time. When
event time arrives, it is removed from the planner. Please note, that
[rotor-light](https://notabug.org/basiliscos/cpp-rotor-light) does not schedules
any events into the planner, so its capacity and usage is completely controlled by
the user code.

How the framework interacts with the planner? If the root supervisor is used in
*poll mode*, then, when there are no more messages left, the current time is
requested, and all timed out event handlers are executed. Then the special message
`refresh-time` is send to the supervisor and the procedure repeats endlessly.
Indirectly, this is similar to the code like:

~~~{.cpp}
while (true) {
  while (has_messages()) {
    auto& message = get_front_message();
    process(message);
    pop_front_message();
  }
  // (22)
  auto now = get_now();
  while (has_expired_events(now)) {
    auto& event = get_next_expired_event(now);
    fire_event(event);
    pop_event(event);
  }
    
~~~

If the *await mode* is used, then user code should implement the whole `while` loop
above and the event awaiting (22) code. This makes it possible to enter into
power-save mode and wake up on external timer or interrupt. See `*-await.cpp`
examples.

In the line (21) the used supervisor is defined: the amount of handlers is specified
(the same as for actor at (5), as each supervisor is an actor) and all its
child actors (including other supervisors) are enumerated. The only `Blinker`
child actor is specified in the current example.

Let's move forward. In the following code [rotor-light](https://notabug.org/basiliscos/cpp-rotor-light)
global variables are allocated:

~~~{.cpp}
Queue queue;
Planner planner;
rl::Context context{&queue, &planner, &get_now};
Supervisor sup;
~~~

All of them can be allocated on the stack, but for the supervisor it is, probably,
the bad idea, because most likely you'll need to access actors from some other
global functions, i.e. ISR, and that can be done only via global supervisor
instance. That might be not obvious, that the supervisor above allocates space for
all its child actors, i.e. *supervisor contains and owns child actors*.

The `get_now()` function pointer refers to a function with the following signature:

~~~{.cpp}
using TimePoint = int64_t;
using NowFunction = TimePoint (*)();
~~~

It is a link to the underlying hardware or system. The function should return
current time; the meaning of "current time" (`TimePoint`) is completely user
specific (i.e. it can point to seconds, milliseconds, microseconds etc.). The only
requirement to the function, that it should be **monotonic**, i.e. do not decrease
nor wrap each next `TimePoint` compared to the previous one. The implementation
of the function is completely platform- or hardware-specific. For the arduino
example it returns the number of microseconds passed since board boot.

The final piece of the current example is:

~~~{.cpp}
int main(int, char **) {
  app_hw_init();

  /* setup */
  sup.bind(context);                        // (23)
  auto blinker = sup.get_child<0>();        // (24)
  blinker->delay = rl::Duration{250000};    // (25)
  /* let it polls timer */
  sup.start(true);                          // (26)

  /* main cycle */
  sup.process();                            // (27)
  return 0;
}
~~~

The context binding (23) let the supervisor know pre-allocated queues, planner and
the `get_now()` function. During context binding all actors get their unique ids,
which can be used. After that individual actors can be accessed (24) with zero
runtime overhead (as it uses `std::get` under the hood) and additional actors
setup can be performed here (26), i.e. delay 1/4 of seconds between LED toggle.

Please note, that setup phase (23-26) need to be performed **only once** despite
of possible multiple actors restarts, i.e. actor identities are preserved during
object lifetimes.

Then, the whole machinery receive initial impulse (26). The `true` value here means
usage of the "poll mode" (see above), i.e. endlessly send self a `refresh-timer`
message, get time, and fire the timed-out events.

In the line (27) supervisor actually starts processing messages, and probably never
exits as soon as everything is going as expected. In the case of *failure
escalation*, i.e. as it tried all possible restarts of actors to recover the
failure, there is nothing left to do than exit and the whole board restart.

## ping-pong messaging, poll timer

In this example how to do messaging with [rotor-light](https://notabug.org/basiliscos/cpp-rotor-light)
is demonstrated: `ping` message is sent from `pinger` actor to `ponger` actor.
The `ponger` actor will reply back with `pong`  message, then after some delay
`pinger` actor repeats the same procedure. The full code can be found at
`examples/atmega328p/ping-pong-poll.cpp`.

First of all used messages should be defined:

~~~{.cpp}
namespace message {
struct Ping : rl::Message {
  using Message::Message;
  static constexpr auto type_id = __LINE__;
};

struct Pong : rl::Message {
  using Message::Message;
  static constexpr auto type_id = __LINE__;
};
} // namespace message
~~~

The `ping` and `pong` messages are content-less, why there is need of them for all?
Because there is need to demonstrate how to send and receive messages and
distinguish them **by type**.

The `Pinger` actor code is:

~~~{.cpp}
struct Pinger : rl::Actor<2> {
  using Parent = Actor<2>;

  void initialize() override {
    subscribe(&Pinger::on_pong); // (28)
    Parent::initialize();
  }

  void advance_start() override {  // (29)
    Parent::advance_start();       // (30)
    ping();                        // (31)
  }

  void ping() {                                          // (32)
    Board::toggle_led();
    send<rl::ctx::thread, message::Ping>(0, ponger_id);  // (33)
  }

  void on_pong(message::Pong &) {                           // (34)
    add_event<rl::ctx::thread>(500000, [](void *data) {     // (35)
      static_cast<Pinger *>(data)->ping();
    }, this);
  }

  rl::ActorId ponger_id;   // (36)
};
~~~

As usually, the `initialize()` should be overridden to subscribe on `pong` messages
(28). The `pinger` actor plays an *active role*, i.e. it sends initial `ping`
message. This is performed in the overridden `advance_start()` method (29), which is
invoked as soon as the actor is ready: the default implementation machinery is
invoked (30), and for convenience `ping()` (31) method is called. The `ping()` (32)
method implementation is simple: after LED toggle, it sends the `ping` message (33).

The `send` method parameters are: the message type (`message::Ping`) template
parameter, message priority (aka destination queue) - `0`, and the destination
actor(s) - ponger actor id, defined at (36). If there are additional message params,
specified in the message type constructor, they should go here.

As soon as `pong` reply is received (34), the ping procedure with LED toggle
is rescheduled after 500000 microseconds (i.e. 0.5 second) at (35).

The `ponger` actor code is rather trivial:

~~~{.cpp}
struct Ponger : rl::Actor<2> {
  using Parent = Actor<2>;

  void initialize() override {
    subscribe(&Ponger::on_ping);
    Parent::initialize();
  }
  void on_ping(message::Ping &) {
    send<rl::ctx::thread, message::Pong>(0, pinger_id);  // (37)
  }
  rl::ActorId pinger_id;   // (38)
};
~~~

as soon `ping` message is received, it replies back (37) with `pong` message. Please
note, while conceptually it "replies back", technically it just sends a new `pong`
message to pinger address, defined at (38). It is important, because there is no
request-response pattern, i.e. it "knows" whom to send back the "reply".

Lets move forward.

~~~{.cpp}
using Supervisor = rl::Supervisor<
    rl::SupervisorBase::min_handlers_amount,
    Pinger,
    Ponger>;
    
using Storage = rl::traits::MessageStorage<rl::message::ChangeState,
                                           rl::message::ChangeStateAck,
                                           message::Ping,
                                           message::Pong>;
~~~

The standard supervisor is used; it owns `pinger` and `ponger` actors. The `Storage`
allocates enough space for `Ping` and `Pong` messages.


~~~{.cpp}
int main(int, char **) {

  app_hw_init();

  /* setup */
  sup.bind(context);
  auto pinger = sup.get_child<0>();      // (39)
  auto ponger = sup.get_child<1>();      // (40)
  pinger->ponger_id = ponger->get_id();  // (41)
  ponger->pinger_id = pinger->get_id();  // (42)
  /* let it polls timer */
  sup.start(true);

  /* main cycle */
  sup.process();   // (43)
  return 0;
}
~~~

The most interesting part is the setup-phase (39-40). `pinger` and `ponger` actors
should know each others addresses, and the addresses are available only after
context binding.

When everything is ready, it enters into main loop (43). In the loop it either
delivers [rotor-light](https://notabug.org/basiliscos/cpp-rotor-light) messages
or waits, until the next event time occurs. It uses **busy waiting** by actively
polling (querying) timer, whether the next event time happend. As usually for
busy waiting, it consumes 100% CPU time, which is common strategy for
embedded/real-time applications.

It is possible however to do something else, instead of endless timer polling, e.g.
do CPU sleep (and consume less current and do less CO2 emission). See the
next section.

## ping-pong messaging, await the next event in power-save mode

The code for this example is located at `examples/atmega328p/ping-pong-await.cpp`.
From user point of view the example does the same as the previous one:
it sends `ping` message, receives `pong` message, blinks with LED and after some
delay the procedure repeats.

However, the notable difference is in the delay: in the previous example it
endlessly polls the timer whether the time arrives for the next event, burning
CPU cycles, in the current example it does energy-efficient sleeping while
there is nothing to do (i.e. no messages) between events.

As the main logic is the same, the actor-related code is also the same; only
`main()` function differs. 

~~~{.cpp}
int main(int, char **) {
  app_hw_init();

  /* allocate */
  Queue queue;
  Planner planner;
  rl::Context context{&queue, &planner, &get_now};
  Supervisor sup;

  /* setup */
  sup.bind(context);
  auto pinger = sup.get_child<0>();
  auto ponger = sup.get_child<1>();
  pinger->ponger_id = ponger->get_id();
  ponger->pinger_id = pinger->get_id();
  /* let it polls timer */
  sup.start(false);  // (44)

  /* main cycle */
  while (true) {                                   // (45)
    sup.process();                                 // (46)
    auto next_event_time = planner.next_event();   // (47)
    if (next_event_time) {                         // (48)
      Board::sleep(next_event_time);               // (49)
    }
  }
  return 0;
}
~~~

Firstly, the timer poll via recursively sending self `refresh-timer` message should
be disabled (44). Then the infinite loop (45) should be started, as the supervisor
exits, when it has no more messages to process (46). The first nearby event should
be extracted from planner (47), if any (48), and then perform platform-specific
sleep until the event. The event handler will be actually processed upon the next
loop iteration in (46).

## integration

Lets suppose, that there is a need to read a custom port on idle or perform some
I/O activity, maybe indirectly via calling some other library on each iteration.
How can that be done?

One of the ways to accomplish that is shown above: disable timer poll and do
the needed activity instead of entering into powersave mode, or in addition to
the powersave mode.

Then second way is to have a custom supervisor with `on_refhesh_timer` method
overridden, like that:

~~~{.cpp}
struct MySupervisor : rl::Supervisor<3, MyActor1, MyActor2, ...> {
using Parent = rl::Supervisor<3, MyActor1, MyActor2, ...>; 

void on_refhesh_timer(rl::message::RefreshTime &message) override {
  Parent::on_refhesh_timer(message);
  third_party_library_poll();
}

};
~~~
